home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tcl / Eval.man < prev    next >
Encoding:
Text File  |  1992-08-07  |  8.4 KB  |  299 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/Eval.man,v 1.8 92/05/01 10:40:44 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tcl_Eval tcl
  189. .BS
  190. .SH NAME
  191. Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
  192. .SH SYNOPSIS
  193. .nf
  194. \fB#include <tcl.h>\fR
  195. .sp
  196. int
  197. \fBTcl_Eval\fR(\fIinterp, cmd, flags, termPtr\fR)
  198. .sp
  199. int
  200. \fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
  201. .sp
  202. int
  203. \fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
  204. .sp
  205. .VS
  206. int
  207. \fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
  208. .VE
  209. .SH ARGUMENTS
  210. .AS Tcl_Interp **termPtr;
  211. .AP Tcl_Interp *interp in
  212. Interpreter in which to execute the command.  String result will be
  213. stored in \fIinterp->result\fR.
  214. .AP char *cmd in
  215. Command (or sequence of commands) to execute.
  216. .AP int flags in
  217. Either \fBTCL_BRACKET_TERM\fR or 0.
  218. If 0, then \fBTcl_Eval\fR will process commands from \fIcmd\fR until
  219. it reaches the null character at the end of the string.
  220. If \fBTCL_BRACKET_TERM\fR,
  221. then \fBTcl_Eval\fR will process comands from \fIcmd\fR until either it
  222. reaches a null character or it encounters a close bracket that isn't
  223. backslashed or enclosed in braces, at which point it will return.
  224. Under normal conditions, \fIflags\fR should be 0.
  225. .AP char **termPtr out
  226. If \fItermPtr\fR is non-NULL, \fBTcl_Eval\fR fills in *\fItermPtr\fR with
  227. the address of the character just after the last one in the last command
  228. successfully executed (normally the null character at the end of \fIcmd\fR).
  229. If an error occurs in the first command in \fIcmd\fR, then \fI*termPtr\fR
  230. will be set to \fIcmd\fR.
  231. .AP char *string in
  232. String forming part of Tcl command.
  233. .AP char *fileName in
  234. Name of file containing Tcl command string.
  235. .BE
  236.  
  237. .SH DESCRIPTION
  238. .PP
  239. All four of these procedures execute Tcl commands.
  240. \fBTcl_Eval\fR is the core procedure:  it parses commands
  241. from \fIcmd\fR and executes them in
  242. order until either an error occurs or \fBTcl_Eval\fR reaches a terminating
  243. character (']' or '\e0', depending on the value of \fIflags\fR).
  244. The return value from \fBTcl_Eval\fR is one
  245. of the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
  246. \fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
  247. a string with additional information (result value or error message).
  248. This return information corresponds to the last command executed from
  249. \fIcmd\fR.
  250. .PP
  251. \fBTcl_VarEval\fR takes any number of string arguments
  252. of any length, concatenates
  253. them into a single string, then calls \fBTcl_Eval\fR to
  254. execute that string as a Tcl command.
  255. It returns the result of the command and also modifies
  256. \fIinterp->result\fR in the usual fashion for Tcl commands.  The
  257. last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
  258. of arguments.
  259. .PP
  260. \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
  261. its contents as a Tcl command by calling \fBTcl_Eval\fR.  It returns
  262. a standard Tcl result that reflects the result of evaluating the
  263. file.
  264. If the file couldn't be read then a Tcl error is returned to describe
  265. why the file couldn't be read.
  266. .PP
  267. .VS
  268. \fBTcl_GlobalEval\fR is similar to \fBTcl_Eval\fR except that it
  269. processes the command at global level.
  270. This means that the variable context for the command consists of
  271. global variables only (it ignores any Tcl procedure that is active).
  272. This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
  273. .VE
  274. .PP
  275. During the processing of a Tcl command it is legal to make nested
  276. calls to evaluate other commands (this is how conditionals, loops,
  277. and procedures are implemented).
  278. If a code other than
  279. \fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
  280. caller should normally return immediately, passing that same
  281. return code back to its caller, and so on until the top-level application is
  282. reached.  A few commands, like \fBfor\fR, will check for certain
  283. return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
  284. specially without returning.
  285. .PP
  286. \fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
  287. in progress for \fIinterp\fR.
  288. If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
  289. about to be returned from the topmost \fBTcl_Eval\fR invocation for
  290. \fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
  291. and sets \fIinterp->result\fR to point to an error message indicating that
  292. the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
  293. invoked in an inappropriate place.  This means that top-level
  294. applications should never see a return code from \fBTcl_Eval\fR other then
  295. \fBTCL_OK\fR or \fBTCL_ERROR\fR.
  296.  
  297. .SH KEYWORDS
  298. command, execute, file, global, interpreter, variable
  299.